Apple II
Sample Code Notes
_____________________________________________________________________________
                                                  Developer Technical Support

#20:    DTS Tools and Libraries

Version:    3.1                                                     June 1990

APW Components:    MPW Components:

DTS.Lib1.v1.0      DTS.Lib1.v1.0
FMD.asm            FakeModalDialog.Aii
FMD.h              FakeModalDialog.h
FMDUserTool.asm    FakeModalDialog.usage
E16.FMD            FakeModalTool
M16.FMD            FMDUserTool.Aii
OffScn.port.asm    E16.FMD
PMUserTool.asm     M16.FMD
PtrCheck.asm       OffScn.port.Aii
PM2Rgn.root        PixMapTool
Full.Build         PixMapTool.usage
Build.DTS.lib      PMUserTool.Aii
Build.FMDTool      PtrCheck.Aii
Build.pMTool       PixelMap2Rgn.Aii.obj
Build.Macros       Make.DTS.Lib1.v1.0
                   Make.FMDTool
                   Make.pMTool

FakeModalTool provides routines for modal and movable-modal dialog boxes, 
while PixMapTool provides off-screen pixelmap support and allows conversion of 
pixelmaps to regions.  Documentation for these routines is forthcoming in a 
manual from APDA and will also be released in the next revision of Apple II 
Sample Code in electronic format.
_____________________________________________________________________________

Although the object code for PixMapTool is included as part of this
sample, you must obtain a license to use it in commercial applications.
You can license redistribution rights for PixMapTool by contacting Apple
Software Licensing:

            Apple Software Licensing
            Apple Computer, Inc.,
            20525 Mariani Avenue, M/S 38-I
            Cupertino, CA, 95014
            (408) 974-4667
            AppleLink:  SW.LICENSE

DTS Tools & Libraries contains the following collections of routines:

FakeModalDialog

FakeModalDialog is a flexible set of routines for dealing with modal dialog
boxes (a modal dialog box is a window which remains in front of other
application windows until the user dismisses it).

The FakeModalDialog routines are provided as assembly-language source code,
in library form, and as a user tool set.  Sample Code #9, Lister, shows how
to use FakeModalDialog from C.  By changing a #define in the file Lister.h,
you can use either the library or the user tool set version (just use #define
to define either _fmdLib_ or _fmdTool_, and fakeModalDialog.h takes care of
generating calls to library routines or user tool functions).

For information on user tool sets, see Appendix A of Apple IIgs Toolbox
Reference, Volume 1, and the Apple IIgs Technical Note #73, Using User Tool
Sets.

There is a small assembly-language file that provides the user-tool wrapper
around the fakeModalDialog routines (the wrapper is called FMDUserTool.aii
under MPW IIgs and FMDUserTool.asm under APW).  The bulk of the wrapper is
glue needed because tool set functions are called with two RTL addresses on
the stack, while the real FakeModalDialog routines, written in C with
Pascal-style calling conventions, require a single RTL address.

PixMapTool

The PixMapTool user tool set includes PixelMap2Rgn and the off-screen pixel
map routines.  The user tool set wrapper, pmUserTool.aii, works very much
like the user tool set wrapper in fakeModalDialog.

PtrCheck

The PtrCheck routines help detect when uninitialized auto pointer variables
are used in APW C or MPW IIgs C.  See the source (PtrCheck.asm or
PtrCheck.aii) for details.

APW 65816 assembly language users need APW v.1.0, APW Tools & Interfaces 
v.1.1, and Apple IIGS System Software 5.0.2 or later.  Five APW command files, 
Full.Build, Build.DTS.lib, Build.FMDTool, Build.PMTool, and Build.macros allow 
you to perform complete or partial rebuilds of the tools.

MPW IIGS users need MPW v.3.0, MPW IIGS Tools v.1.1, and the MPW IIGS Assembler 
v.1.0 or later.  Three MakeFiles, Make.DTS.Lib1.v1.0, Make.FMDTool, and 
Make.PMTool allow you to perform complete or partial rebuilds of the tools.
